ES|QL: Add TRANGE ES|QL function #136441

leontyevdv · 2025-10-11T00:02:58Z

Add a new ES|QL function that filters @timestamp values for the given time range.

TRANGE(<start time>, <end time>)
TRANGE(<time interval>)

Filters @timestamp values for the given time range. The first version implicitly uses now() as end time, giving an interval for the last hour or day, while the second one can consume regular DateTime specs or negative intervals:

TRANGE(1h) is equivalent to @timestamp >= now() - 1 hour

TRANGE(-3h, -2h) is equivalent to @timestamp >= now() - 3 hour AND @timestamp < now() - 2h

TRANGE(2024-05-12T12:00:00, 2024-05-12T15:30:00) is equivalent to @timestamp >= DATE_PARSE(2024-05-12T12:00:00) AND @timestamp < DATE_PARSE(2024-05-12T15:30:00)

TRANGE(1715504400000, 1715517000000) is equivalent to the above, using ms since Epoch instead of text-formatted dates.

Closes #135599

@timestamp

Add a new ES|QL function that filters @timestamp values for the given time range. Closes elastic#135599

elasticsearchmachine · 2025-10-11T00:03:23Z

Pinging @elastic/es-analytical-engine (Team:Analytics)

elasticsearchmachine · 2025-10-11T00:03:24Z

Pinging @elastic/es-storage-engine (Team:StorageEngine)

elasticsearchmachine · 2025-10-11T00:03:46Z

Hi @leontyevdv, I've created a changelog YAML for you.

github-actions · 2025-10-11T00:05:37Z

🔍 Preview links for changed docs

docs/reference/query-languages/esql/kibana/docs/functions/trange.md

github-actions · 2025-10-11T00:05:38Z

ℹ️ Important: Docs version tagging

👋 Thanks for updating the docs! Just a friendly reminder that our docs are now cumulative. This means all 9.x versions are documented on the same page and published off of the main branch, instead of creating separate pages for each minor version.

We use applies_to tags to mark version-specific features and changes.

Expand for a quick overview

When to use applies_to tags:

✅ At the page level to indicate which products/deployments the content applies to (mandatory)
✅ When features change state (e.g. preview, ga) in a specific version
✅ When availability differs across deployments and environments

What NOT to do:

❌ Don't remove or replace information that applies to an older version
❌ Don't add new information that applies to a specific version without an applies_to tag
❌ Don't forget that applies_to tags can be used at the page, section, and inline level

🤔 Need help?

Check out the cumulative docs guidelines
Reach out in the #docs Slack channel

@timestamp

Add a new ES|QL function that filters @timestamp values for the given time range. Closes elastic#135599

dnhatn · 2025-10-12T16:15:43Z

Thank you, Dima! Is there a reason we don't translate TRANGE to GreaterThanEquals() or BinaryLogicOperation(GreaterThanEquals, LessThanOrEquals)?

leontyevdv · 2025-10-14T10:16:22Z

Thank you, Dima! Is there a reason we don't translate TRANGE to GreaterThanEquals() or BinaryLogicOperation(GreaterThanEquals, LessThanOrEquals)?

Hi @dnhatn ! Thank you for the review! Initially, I implemented TRANGE as a surrogate and struggled with the tests for quite a while. The issue was with the assertion ("Duplicate name ids are not allowed in layouts"): see Layout. Then, inspired by the StartsWith function, I rewrote it using TranslationAware.SingleValueTranslationAware directly.

I have the surrogate version in my stash. We can take a look at it together. Wdyt?

Fix tests. Closes elastic#135599

# Conflicts: # x-pack/plugin/esql/qa/testFixtures/src/main/resources/k8s-timeseries-rate.csv-spec # x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/action/EsqlCapabilities.java

Replace asQuery by a surrogate Closes elastic#135599

Fix tests Closes elastic#135599

Fix constructor visibility Closes elastic#135599

Fix tests Closes elastic#135599

dnhatn

Thanks Dima! I left some comments, but the PR looks promising.

I have a few use cases we might need to discuss:

Modifier: Limit time range to one hour from "2025-01-04T07:40:00+00:00"?
Offset: Limit time range to 1 hour a week from now: TRANGE(1w + 1h, 1w). I'm not sure if this is valid syntax. Can we provide a better syntax?
Start only: TRANGE("2025-01-04T07:40:00+00:00"), which means TRANGE("2025-01-04T07:40:00+00:00", now)?

dnhatn · 2025-10-15T15:35:27Z

.../esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/date/TRange.java

+
+        resolution = isType(
+            startTime,
+            dt -> dt == KEYWORD || dt == LONG || dt == INTEGER,


Not sure why we allow longs and ints here?

dnhatn · 2025-10-15T15:36:27Z

.../esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/date/TRange.java

+        if (endTime == null) {
+            Object start = startTime.fold(foldContext);
+            if (start == null) {
+                throw new InvalidArgumentException("start_time_or_interval can not be null in [{}]", sourceText());


I think we prefer reporting this in PostAnalysisVerificationAware. Can you implement PostAnalysisVerificationAware for this class?

kkrik-es · 2025-10-16T12:49:51Z

Offset: Limit time range to 1 hour a week from now: TRANGE(1w + 1h, 1w). I'm not sure if this is valid syntax. Can we provide a better syntax?

This one is interesting.. I'd say we leave this for later, as the semantics are more elaborate. @dnhatn wdyt?

The rest should be fine.

leontyevdv · 2025-10-16T13:05:12Z

Offset: Limit time range to 1 hour a week from now: TRANGE(1w + 1h, 1w). I'm not sure if this is valid syntax. Can we provide a better syntax?

This one is interesting.. I'd say we leave this for later, as the semantics are more elaborate. @dnhatn wdyt?

The rest should be fine.

Thanks, folks! To confirm what I'm going to add and what have been implemented already:

[DONE] TRANGE(2024-05-12T12:00:00, 2024-05-12T15:30:00) - [explicit start; explicit end]
[DONE] TRANGE(1715504400000, 1715517000000) - [explicit start in millis; explicit end in millis]
[DONE] TRANGE(1h) - [now - 1h; now] - supports time_duration (1h, 1min, etc) and period (1day, 1month, etc.)

Explicit start time until Now:
[TODO] TRANGE(2024-05-12T12:00:00) - [explicit start; now]
[TODO] TRANGE(1715504400000) - [explicit start in millis; now]

Modifier for an explicit start time:
[TODO] TRANGE(2024-05-12T12:00:00, 1h) - [explicit start; start + 1h] - supports time_duration (1h, 1min, etc) and period (1day, 1month, etc.)
[TODO] TRANGE(2024-05-12T12:00:00, -1h) - [explicit start; start - 1h] - supports time_duration (1h, 1min, etc) and period (1day, 1month, etc.)

Does this make sense?

ES|QL: Add TRANGE ES|QL function

b89f498

Add a new ES|QL function that filters @timestamp values for the given time range. Closes elastic#135599

leontyevdv requested a review from dnhatn October 11, 2025 00:02

leontyevdv self-assigned this Oct 11, 2025

leontyevdv added >enhancement Team:Analytics Meta label for analytical engine team (ESQL/Aggs/Geo) :StorageEngine/TSDB You know, for Metrics :Analytics/ES|QL AKA ESQL Team:StorageEngine :StorageEngine/ES|QL Timeseries / metrics / logsdb capabilities in ES|QL labels Oct 11, 2025

elasticsearchmachine added the v9.3.0 label Oct 11, 2025

Update docs/changelog/136441.yaml

6d8cc81

github-actions bot deployed to docs-preview October 11, 2025 00:04 View deployment

leontyevdv requested a review from a team October 11, 2025 00:10

ES|QL: Add TRANGE ES|QL function

063f72b

Add a new ES|QL function that filters @timestamp values for the given time range. Closes elastic#135599

github-actions bot deployed to docs-preview October 11, 2025 00:31 View deployment

leontyevdv added 2 commits October 14, 2025 15:13

ES|QL: Add TRANGE ES|QL function

e42b1ca

Fix tests. Closes elastic#135599

Merge branch 'main' into feature/esql-trange-function

f4c694f

# Conflicts: # x-pack/plugin/esql/qa/testFixtures/src/main/resources/k8s-timeseries-rate.csv-spec # x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/action/EsqlCapabilities.java

github-actions bot deployed to docs-preview October 14, 2025 13:16 View deployment

ES|QL: Add TRANGE ES|QL function

5642817

Replace asQuery by a surrogate Closes elastic#135599

github-actions bot deployed to docs-preview October 14, 2025 15:23 View deployment

ES|QL: Add TRANGE ES|QL function

736194e

Replace asQuery by a surrogate Closes elastic#135599

github-actions bot deployed to docs-preview October 15, 2025 11:10 View deployment

ES|QL: Add TRANGE ES|QL function

ea9e431

Fix tests Closes elastic#135599

github-actions bot deployed to docs-preview October 15, 2025 12:08 View deployment

ES|QL: Add TRANGE ES|QL function

e572f55

Fix constructor visibility Closes elastic#135599

github-actions bot deployed to docs-preview October 15, 2025 14:19 View deployment

leontyevdv added 2 commits October 15, 2025 17:09

Merge branch 'main' into feature/esql-trange-function

ec90dc5

ES|QL: Add TRANGE ES|QL function

9b0aa07

Fix tests Closes elastic#135599

github-actions bot deployed to docs-preview October 15, 2025 15:25 View deployment

leontyevdv requested a review from bpintea October 15, 2025 15:51

dnhatn reviewed Oct 15, 2025

View reviewed changes

dnhatn self-requested a review October 15, 2025 16:17

ES|QL: Add TRANGE ES|QL function #136441

Are you sure you want to change the base?

ES|QL: Add TRANGE ES|QL function #136441

Conversation

leontyevdv commented Oct 11, 2025

Uh oh!

elasticsearchmachine commented Oct 11, 2025

Uh oh!

elasticsearchmachine commented Oct 11, 2025

Uh oh!

elasticsearchmachine commented Oct 11, 2025

Uh oh!

github-actions bot commented Oct 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

github-actions bot commented Oct 11, 2025

ℹ️ Important: Docs version tagging

When to use applies_to tags:

What NOT to do:

🤔 Need help?

Uh oh!

dnhatn commented Oct 12, 2025

Uh oh!

leontyevdv commented Oct 14, 2025

Uh oh!

dnhatn left a comment

Choose a reason for hiding this comment

Uh oh!

dnhatn Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

dnhatn Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

kkrik-es commented Oct 16, 2025

Uh oh!

leontyevdv commented Oct 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions bot commented Oct 11, 2025 •

edited

Loading

leontyevdv commented Oct 16, 2025 •

edited

Loading